add EmuContractExecutor (sierra-emu backend, interchangeable with AotContractExecutor) by avi-starkware · Pull Request #1612 · starkware-libs/cairo_native

avi-starkware · 2026-05-14T07:40:35Z

Summary

Makes the sierra-emu interpreter usable as a drop-in alternative to AotContractExecutor at contract call sites — without a dispatch enum. No consumer selects a backend at runtime (the choice is always made per build by feature flags), so consumers pick an executor type per build instead of wrapping every executor in an enum on the production path.

An earlier revision of this PR introduced a ContractExecutor dispatch enum (Aot + Emu); per review it's gone — no consumer, in-tree or out, ever picked a variant at runtime, so the enum's match was ceremony around a decision the build's feature flags had already made.

Changes

debug_utils/sierra-emu: new VirtualMachine::run_contract(...) — one-shot convenience over new_starknet + call_contract + run. Returns None when the VM never produced a final state.
src/executor/emu_contract_executor.rs (new, gated on the new sierra-emu cargo feature): EmuContractExecutor { program, entry_points, sierra_version } with an inherent run() that mirrors AotContractExecutor::run — same parameter shape, same StarknetSyscallHandler trait (shared via cairo-native-syscalls, so the handler flows through unchanged). Converts BuiltinCosts and the emu result into cairo-native's ContractExecutionResult (with default builtin_stats).
Cargo.toml: new sierra-emu = ["dep:sierra-emu"] feature; with-trace-dump now depends on the feature rather than the optional dep directly.

Stack

align sierra-emu StarknetSyscallHandler trait/types with cairo-native #1610 — trait alignment
extract shared cairo-native-syscalls crate #1611 — extract shared crate
this PR — sierra-emu contract executor
add run_with_libfunc_profile + AotWithProgram pairing #1613 — run_with_libfunc_profile + AotWithProgram

Test plan

cargo check (default features) clean
cargo check --features sierra-emu clean
cargo check --workspace --all-features clean (on stack tip)
CI green

This change is

github-actions · 2026-05-14T07:41:07Z

✅ Code is now correctly formatted.

orizi

@orizi made 1 comment.
Reviewable status: 0 of 23 files reviewed, 1 unresolved discussion (waiting on avi-starkware, TomerStarkware, and Yoni-Starkware).

-- commits line 1 at r2:
is this missing a rebase?

github-actions · 2026-07-05T08:38:11Z

Benchmarking results

Benchmark for program `dict_insert`

Open benchmarks

Command	Mean [s]	Min [s]	Max [s]	Relative
`Cairo-vm (Rust, Cairo 1)`	10.644 ± 0.209	10.461	11.181	5.75 ± 0.12
`cairo-native (embedded AOT)`	1.852 ± 0.015	1.825	1.869	1.00
`cairo-native (embedded JIT using LLVM's ORC Engine)`	1.870 ± 0.020	1.850	1.910	1.01 ± 0.01

Benchmark for program `dict_snapshot`

Open benchmarks

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
`Cairo-vm (Rust, Cairo 1)`	515.1 ± 2.2	512.9	519.3	1.00
`cairo-native (embedded AOT)`	1601.1 ± 11.6	1584.5	1619.4	3.11 ± 0.03
`cairo-native (embedded JIT using LLVM's ORC Engine)`	1632.1 ± 13.5	1618.4	1661.9	3.17 ± 0.03

Benchmark for program `factorial_2M`

Open benchmarks

Command	Mean [s]	Min [s]	Max [s]	Relative
`Cairo-vm (Rust, Cairo 1)`	4.657 ± 0.013	4.639	4.679	2.77 ± 0.03
`cairo-native (embedded AOT)`	1.682 ± 0.016	1.660	1.715	1.00
`cairo-native (embedded JIT using LLVM's ORC Engine)`	1.700 ± 0.023	1.677	1.747	1.01 ± 0.02

Benchmark for program `fib_2M`

Open benchmarks

Command	Mean [s]	Min [s]	Max [s]	Relative
`Cairo-vm (Rust, Cairo 1)`	4.579 ± 0.016	4.549	4.603	2.83 ± 0.03
`cairo-native (embedded AOT)`	1.619 ± 0.017	1.595	1.648	1.00
`cairo-native (embedded JIT using LLVM's ORC Engine)`	1.645 ± 0.011	1.630	1.667	1.02 ± 0.01

Benchmark for program `linear_search`

Open benchmarks

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
`Cairo-vm (Rust, Cairo 1)`	561.3 ± 6.2	552.7	571.8	1.00
`cairo-native (embedded AOT)`	1637.1 ± 9.4	1626.6	1653.4	2.92 ± 0.04
`cairo-native (embedded JIT using LLVM's ORC Engine)`	1673.5 ± 14.7	1658.3	1703.4	2.98 ± 0.04

Benchmark for program `logistic_map`

Open benchmarks

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
`Cairo-vm (Rust, Cairo 1)`	478.7 ± 7.7	466.7	491.8	1.00
`cairo-native (embedded AOT)`	1606.7 ± 10.2	1584.7	1621.7	3.36 ± 0.06
`cairo-native (embedded JIT using LLVM's ORC Engine)`	1625.1 ± 7.5	1615.4	1637.5	3.39 ± 0.06

github-actions · 2026-07-05T08:41:40Z

Benchmark results Main vs HEAD.

Base

Command	Mean [s]	Min [s]	Max [s]	Relative
`base dict_insert.cairo (JIT)`	1.788 ± 0.005	1.780	1.794	1.00 ± 0.01
`base dict_insert.cairo (AOT)`	1.783 ± 0.008	1.772	1.798	1.00

Head

Command	Mean [s]	Min [s]	Max [s]	Relative
`head dict_insert.cairo (JIT)`	2.010 ± 0.042	1.959	2.080	1.00
`head dict_insert.cairo (AOT)`	2.018 ± 0.042	1.967	2.097	1.00 ± 0.03

Base

Command	Mean [s]	Min [s]	Max [s]	Relative
`base dict_snapshot.cairo (JIT)`	1.618 ± 0.011	1.600	1.633	1.02 ± 0.01
`base dict_snapshot.cairo (AOT)`	1.592 ± 0.012	1.579	1.614	1.00

Head

Command	Mean [s]	Min [s]	Max [s]	Relative
`head dict_snapshot.cairo (JIT)`	1.793 ± 0.046	1.753	1.889	1.00
`head dict_snapshot.cairo (AOT)`	1.817 ± 0.044	1.761	1.903	1.01 ± 0.04

Base

Command	Mean [s]	Min [s]	Max [s]	Relative
`base factorial_2M.cairo (JIT)`	1.676 ± 0.012	1.654	1.690	1.01 ± 0.01
`base factorial_2M.cairo (AOT)`	1.659 ± 0.017	1.633	1.690	1.00

Head

Command	Mean [s]	Min [s]	Max [s]	Relative
`head factorial_2M.cairo (JIT)`	1.888 ± 0.033	1.833	1.937	1.03 ± 0.03
`head factorial_2M.cairo (AOT)`	1.841 ± 0.032	1.792	1.885	1.00

Base

Command	Mean [s]	Min [s]	Max [s]	Relative
`base fib_2M.cairo (JIT)`	1.615 ± 0.005	1.609	1.622	1.01 ± 0.01
`base fib_2M.cairo (AOT)`	1.594 ± 0.013	1.580	1.618	1.00

Head

Command	Mean [s]	Min [s]	Max [s]	Relative
`head fib_2M.cairo (JIT)`	1.761 ± 0.028	1.711	1.811	1.00 ± 0.02
`head fib_2M.cairo (AOT)`	1.760 ± 0.014	1.737	1.776	1.00

Base

Command	Mean [s]	Min [s]	Max [s]	Relative
`base linear_search.cairo (JIT)`	1.640 ± 0.011	1.624	1.659	1.02 ± 0.01
`base linear_search.cairo (AOT)`	1.607 ± 0.011	1.586	1.619	1.00

Head

Command	Mean [s]	Min [s]	Max [s]	Relative
`head linear_search.cairo (JIT)`	1.874 ± 0.024	1.828	1.901	1.05 ± 0.03
`head linear_search.cairo (AOT)`	1.791 ± 0.039	1.742	1.876	1.00

Base

Command	Mean [s]	Min [s]	Max [s]	Relative
`base logistic_map.cairo (JIT)`	1.624 ± 0.007	1.612	1.632	1.02 ± 0.01
`base logistic_map.cairo (AOT)`	1.592 ± 0.011	1.578	1.608	1.00

Head

Command	Mean [s]	Min [s]	Max [s]	Relative
`head logistic_map.cairo (JIT)`	1.834 ± 0.032	1.803	1.890	1.04 ± 0.02
`head logistic_map.cairo (AOT)`	1.767 ± 0.028	1.718	1.806	1.00

avi-starkware · 2026-07-05T09:17:53Z

-- commits line 1 at r2:

Previously, orizi wrote…

is this missing a rebase?

Done.

orizi

@orizi reviewed 22 files and all commit messages, and made 1 comment.
Reviewable status: 22 of 23 files reviewed, 2 unresolved discussions (waiting on avi-starkware, TomerStarkware, and Yoni-Starkware).

src/executor/contract_executor.rs line 107 at r3 (raw file):

                    builtin_stats: Default::default(),
                })
            }

any reason to not just add this into sierra-emu and not need this entire new execute file?

Code quote:

                let mut virtual_machine = sierra_emu::VirtualMachine::new_starknet(
                    Arc::clone(program),
                    entry_points,
                    *sierra_version,
                );

                let emu_builtin_costs = builtin_costs.map(convert_builtin_costs);

                virtual_machine.call_contract(selector, gas, args.to_vec(), emu_builtin_costs);

                // `VirtualMachine::run` returns `None` when the VM never produced a
                // final state -- propagate as an error rather than aborting the host.
                let result = virtual_machine.run(&mut syscall_handler).ok_or_else(|| {
                    Error::UnexpectedValue("sierra-emu VM produced no final state".to_string())
                })?;

                Ok(ContractExecutionResult {
                    remaining_gas: result.remaining_gas,
                    failure_flag: result.failure_flag,
                    return_values: result.return_values,
                    error_msg: result.error_msg,
                    builtin_stats: Default::default(),
                })
            }

avi-starkware · 2026-07-06T13:50:13Z

src/executor/contract_executor.rs line 107 at r3 (raw file):

Previously, orizi wrote…

any reason to not just add this into sierra-emu and not need this entire new execute file?

I removed the ContractExecutor enum and replaced it with a type alias (also removed this file).

I looked at the code and at how lambdaclass used it for replay, and there is no dynamic dispatch of Contract executor types. The type used is determined at compile time. So I think we can safely remove this.

orizi

@orizi made 1 comment.
Reviewable status: 21 of 25 files reviewed, 2 unresolved discussions (waiting on avi-starkware, TomerStarkware, and Yoni-Starkware).

-- commits line 1 at r2:

Previously, avi-starkware (Avi Cohen) wrote…

Done.

are you sure? this seems to contain 4 commits.

orizi

@orizi reviewed 4 files and resolved 1 discussion.
Reviewable status: all files reviewed (commit messages unreviewed), 1 unresolved discussion (waiting on avi-starkware, TomerStarkware, and Yoni-Starkware).

Mirrors AotContractExecutor::run so the two are interchangeable at call sites. sierra_emu::VirtualMachine::run_contract owns the new_starknet + call_contract + run sequence; this crate only converts BuiltinCosts and the result type at the seam. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

avi-starkware

@avi-starkware made 1 comment.
Reviewable status: all files reviewed (commit messages unreviewed), 1 unresolved discussion (waiting on orizi, TomerStarkware, and Yoni-Starkware).

-- commits line 1 at r2:

Previously, orizi wrote…

are you sure? this seems to contain 4 commits.

Done.

orizi

@orizi reviewed all commit messages, made 1 comment, and resolved 1 discussion.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on TomerStarkware and Yoni-Starkware).

avi-starkware mentioned this pull request May 14, 2026

add run_with_libfunc_profile + AotWithProgram pairing #1613

Merged

5 tasks

avi-starkware force-pushed the avi/cairo_native/syscall-types-crate branch from b3a574c to 319a6be Compare May 14, 2026 12:26

avi-starkware force-pushed the avi/cairo_native/contract-executor-2 branch from 98ed085 to 64c12b3 Compare May 14, 2026 12:26

avi-starkware force-pushed the avi/cairo_native/syscall-types-crate branch from 319a6be to 92ecf03 Compare May 14, 2026 12:33

avi-starkware force-pushed the avi/cairo_native/contract-executor-2 branch from 64c12b3 to 7e5fcd7 Compare May 14, 2026 12:33

avi-starkware requested review from TomerStarkware, Yoni-Starkware and orizi May 17, 2026 08:15

avi-starkware force-pushed the avi/cairo_native/syscall-types-crate branch from 92ecf03 to 3b3e5af Compare May 17, 2026 11:57

avi-starkware force-pushed the avi/cairo_native/contract-executor-2 branch from 7e5fcd7 to 4176352 Compare May 17, 2026 11:57

avi-starkware force-pushed the avi/cairo_native/syscall-types-crate branch from 3b3e5af to 24f61ba Compare May 17, 2026 12:08

avi-starkware force-pushed the avi/cairo_native/contract-executor-2 branch from 4176352 to 7af0508 Compare May 17, 2026 12:08

avi-starkware force-pushed the avi/cairo_native/syscall-types-crate branch from 24f61ba to 0ae0d06 Compare May 17, 2026 13:24

avi-starkware force-pushed the avi/cairo_native/contract-executor-2 branch from 7af0508 to 38c5f2f Compare May 17, 2026 13:24

avi-starkware force-pushed the avi/cairo_native/syscall-types-crate branch from 0ae0d06 to 0791b36 Compare May 17, 2026 13:27

avi-starkware force-pushed the avi/cairo_native/contract-executor-2 branch from 38c5f2f to 81093b3 Compare May 17, 2026 13:27

avi-starkware force-pushed the avi/cairo_native/syscall-types-crate branch from 0791b36 to 4e80562 Compare May 17, 2026 13:58

avi-starkware force-pushed the avi/cairo_native/contract-executor-2 branch 2 times, most recently from 4f53f27 to 6f77130 Compare May 20, 2026 09:43

avi-starkware force-pushed the avi/cairo_native/syscall-types-crate branch from 4e80562 to 34f9e15 Compare May 20, 2026 09:43

This was referenced May 20, 2026

align sierra-emu StarknetSyscallHandler trait/types with cairo-native #1610

Merged

extract shared cairo-native-syscalls crate #1611

Merged

blockifier: adopt cairo-native executors via cfg-resolved NativeContractExecutor starkware-libs/sequencer#13880

Open

avi-starkware force-pushed the avi/cairo_native/syscall-types-crate branch from 34f9e15 to eec22ef Compare May 28, 2026 14:56

avi-starkware force-pushed the avi/cairo_native/contract-executor-2 branch 2 times, most recently from aa4bf47 to e6a4ad9 Compare May 31, 2026 12:03

avi-starkware force-pushed the avi/cairo_native/syscall-types-crate branch from eec22ef to 487deb9 Compare May 31, 2026 12:03

avi-starkware force-pushed the avi/cairo_native/contract-executor-2 branch 2 times, most recently from 538f655 to c8ed1f7 Compare June 1, 2026 11:26

avi-starkware force-pushed the avi/cairo_native/syscall-types-crate branch from 701a87c to 61059c1 Compare June 1, 2026 11:26

Base automatically changed from avi/cairo_native/syscall-types-crate to main June 1, 2026 13:59

orizi requested changes Jun 7, 2026

View reviewed changes

avi-starkware force-pushed the avi/cairo_native/contract-executor-2 branch from c8ed1f7 to 90cd01f Compare July 5, 2026 08:04

avi-starkware force-pushed the avi/cairo_native/contract-executor-2 branch from 90cd01f to a1e3635 Compare July 5, 2026 09:00

orizi requested changes Jul 5, 2026

View reviewed changes

avi-starkware changed the title ~~add ContractExecutor dispatch enum (Aot + Emu)~~ add EmuContractExecutor (sierra-emu backend, interchangeable with AotContractExecutor) Jul 6, 2026

orizi requested changes Jul 19, 2026

View reviewed changes

orizi reviewed Jul 20, 2026

View reviewed changes

avi-starkware force-pushed the avi/cairo_native/contract-executor-2 branch from 4fdd841 to f62b57a Compare July 20, 2026 09:50

avi-starkware commented Jul 20, 2026

View reviewed changes

orizi approved these changes Jul 20, 2026

View reviewed changes

TomerStarkware added this pull request to the merge queue Jul 20, 2026

Merged via the queue into main with commit b2a6cf8 Jul 20, 2026
15 checks passed

TomerStarkware deleted the avi/cairo_native/contract-executor-2 branch July 20, 2026 11:42

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

add EmuContractExecutor (sierra-emu backend, interchangeable with AotContractExecutor)#1612

add EmuContractExecutor (sierra-emu backend, interchangeable with AotContractExecutor)#1612
TomerStarkware merged 1 commit into
mainfrom
avi/cairo_native/contract-executor-2

avi-starkware commented May 14, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 14, 2026 •

edited

Loading

Uh oh!

orizi left a comment

Uh oh!

github-actions Bot commented Jul 5, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 5, 2026 •

edited

Loading

Uh oh!

avi-starkware commented Jul 5, 2026

Uh oh!

orizi left a comment

Uh oh!

avi-starkware commented Jul 6, 2026

Uh oh!

orizi left a comment

Uh oh!

orizi left a comment

Uh oh!

avi-starkware left a comment

Uh oh!

orizi left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

avi-starkware commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Stack

Test plan

Uh oh!

github-actions Bot commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

orizi left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jul 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Benchmarking results

Benchmark for program dict_insert

Benchmark for program dict_snapshot

Benchmark for program factorial_2M

Benchmark for program fib_2M

Benchmark for program linear_search

Benchmark for program logistic_map

Uh oh!

github-actions Bot commented Jul 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Benchmark results Main vs HEAD.

Base

Head

Base

Head

Base

Head

Base

Head

Base

Head

Base

Head

Uh oh!

avi-starkware commented Jul 5, 2026

Uh oh!

orizi left a comment

Choose a reason for hiding this comment

Uh oh!

avi-starkware commented Jul 6, 2026

Uh oh!

orizi left a comment

Choose a reason for hiding this comment

Uh oh!

orizi left a comment

Choose a reason for hiding this comment

Uh oh!

avi-starkware left a comment

Choose a reason for hiding this comment

Uh oh!

orizi left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

avi-starkware commented May 14, 2026 •

edited

Loading

github-actions Bot commented May 14, 2026 •

edited

Loading

github-actions Bot commented Jul 5, 2026 •

edited

Loading

Benchmark for program `dict_insert`

Benchmark for program `dict_snapshot`

Benchmark for program `factorial_2M`

Benchmark for program `fib_2M`

Benchmark for program `linear_search`

Benchmark for program `logistic_map`

github-actions Bot commented Jul 5, 2026 •

edited

Loading